Using SSL Encryption

If your SequeLink environment requires greater data privacy than that provided by fixed-key DES, fixed-key 3DES, or byteswap, you can use SSL to encrypt data exchanged between the JDBC Client and the SequeLink Server. This assumes that the communication between the SequeLink Client machine (for applets, the Web server from which the applets are downloaded) and the SequeLink Server machine is secure, meaning that:

Only authorized persons can obtain login access to the Web server machine.
Only authorized persons can eavesdrop on (or monitor) the communication (physical communication lines and any intermediate routers) between the Web server host and the database server host. Because the data on your Intranet is not encrypted, you also must ensure that only authorized access to internal communication lines and internal routers is permitted.

NOTE: SequeLink data scrambling (fixed-key DES, fixed-key 3DES, and byteswap) can work with SSL, resulting in a completely secure combination between the SequeLink Client for JDBC and the SequeLink Server.

Using SSL with a Java application running on your Intranet, you can secure data over your entire network by installing the SequeLink Proxy Server on the same machine as the SequeLink Server (as shown in Figure 14-2) and specifying localhost as the host name of the SequeLink Server in the proxy server configuration file. The cleartext messages that are sent between the SequeLink Proxy Server and the SequeLink Server do not leave the machine.

Figure 14-2. Using SSL with the SequeLink Proxy Server Installed on the SequeLink Server

NOTE: SequeLink Proxy Server uses the IETF TLS (Transport Layer Security) 1.0 standard, the successor to the SSL 3.0 protocol.

SSL Cipher Suites

SSL cipher suite definitions have the format:

SSL_KeyExchangeMethod_WITH_DataTranserCipher_DigestFunction

The following cryptographic strong SSL cipher suites are supported by SequeLink when using SSL with the SequeLink Proxy Serve.

SSL_DH_anon_WITH_RC4_128_MD5
SSL_DH_anon_WITH_3DES_EDE_CBC_SHA
SSL_DH_anon_WITH_DES_CBC_SHA
SSL_DHE_DSS_WITH_3DES_EDE_CBC_SHA
SSL_DHE_DSS_WITH_DES_CBC_SHA
SSL_DHE_DSS_WITH_RC4_128_SHA
SSL_DHE_RSA_WITH_3DES_EDE_CBC_SHA
SSL_DHE_RSA_WITH_DES_CBC_SHA
SSL_RSA_WITH_3DES_EDE_CBC_SHA
SSL_RSA_WITH_DES_CBC_SHA
SSL_RSA_WITH_RC4_128_MD5
SSL_RSA_WITH_RC4_128_SHA

Cryptographic Characteristics of Key Exchange Algorithms

Table 14-1 lists the cryptographic characteristics of SSL key exchange algorithms, including a description, the key-size limit, and the type of situation for which specific algorithms are most appropriate.

Table 14-1. Cryptographic Characteristics of Key Exchange Algorithms 

Key Exchange Algorithm	Description	When to Use
DH_anon	The Diffie-Hellman parameters are generated during session establishment.	When there is no risk of man-in-the-middle attacks.
DHE_DSS	The Diffie-Hellman parameters are generated during session establishment. They are signed by the DSS certificate.	When the DSS certificate of the server is used for signing only and not used for key exchange.
DHE_RSA	The Diffie-Hellman parameters are generated during session establishment. They are signed by the RSA certificate.	When the RSA certificate of the server is used for signing only and not used for key exchange.
RSA	The public key from the RSA certificate is used for key exchange.	When the server uses an RSA certificate.

Cryptographic Characteristics of Data Transfer Ciphers

Table 14-2 lists the cryptographic characteristics of data transfer ciphers, including the algorithm used and the effective key size.

Table 14-2. Cryptographic Characteristics of Data Transfer Ciphers

Data Transfer Cipher	Algorithm	Effective Key size
DES_CBC	DES in cipher block chaining mode	56
3DES_EDE_CBC	Triple DES in cipher block chaining mode	168
RC4	RC4 from RSA	128

Configuring SSL Encryption for the SequeLink^® Proxy Server

You configure SSL encryption in the proxy server configuration file by adding the keyword=value pairs:

Network=ssl 
CipherSuites=value 

NOTES:

The Network and CipherSuites keywords in the proxy server configuration file are case-sensitive.
If you do not want to use SSL, specify Network=socket in the proxy server configuration file or omit the Network keyword from the configuration file.
The value of the CipherSuites keyword is a list of cipher suites to use, in order of preference. The listed cipher suites are separated by commas with no blank spaces allowed. You must specify cipher suites that use the same type of certificate. For example, you cannot specify a combination of RSA cipher suites and DSS cipher suites. See "SSL Cipher Suites" for a list of supported cipher suites.
For cipher suites that require a DSS or RSA certificate, you must specify the X.509 certificate (with the public key) and the corresponding private key in the proxy server configuration file. See Table 14-3 for a list of the keyword=value pairs you can specify in the proxy server configuration file for each key exchange algorithm.
When the JDBC Client and the SequeLink Proxy Server agree on a cipher suite that requires a certificate, the JDBC Client must specify the certificate checker class that will be used to verify the certificate chain the SequeLink Proxy Server sends to the JDBC Client. See "Verifying the SequeLink® Proxy Server Certificate" for more information on certificate checker classes.

Table 14-3 lists the key exchange algorithms you can use and the keyword=value pairs you can specify in the proxy server configuration file when using a particular key exchange algorithm.

Table 14-3. Key Exchange Algorithms and Keyword/Value Pairs for
the SequeLink Proxy Server  

Key Exchange Algorithm	Keyword	Value
DHE_DSS	DSSCertificate	Name of the file with the DSS certificate in DER format or a PKCS #7 certificate chain.
	DSSPrivateKey	Name of the file with the DSS private key in PKCS #8 encrypted format.
	PassPhrase	Pass phrase with which the private key file is encrypted. If this keyword is unspecified, the Proxy Server will prompt for the pass phrase.
	UsePassPhraseDialog	To be prompted for the pass phrase using the standard input/output instead of a dialog box, set this keyword to No. Remember that the pass phrase will be shown on the screen as you type.
DHE_RSA	RSACertificate	Name of the file with the RSA certificate in DER format or a PKCS #7 certificate chain.
	RSAPrivateKey	Name of the file with the RSA private key in PKCS #8 encrypted format.
	PassPhrase	Pass phrase with which the private key file is encrypted. If this keyword is unspecified, the Proxy Server will prompt for the pass phrase.
	UsePassPhraseDialog	To be prompted for the pass phrase using the standard input/output instead of a dialog box, set this keyword to No. Remember that the pass phrase will be shown on the screen as you type.
RSA	RSACertificate	Name of the file with the RSA certificate in DER format or a PKCS #7 certificate chain.
	RSAPrivateKey	Name of the file with the RSA private key in PKCS #8 encrypted format.
	PassPhrase	Pass phrase with which the private key file is encrypted. If this keyword is unspecified, the Proxy Server will prompt for the pass phrase.
	UsePassPhraseDialog	To be prompted for the pass phrase using the standard input/output instead of a dialog box, set this keyword to No. Remember that the pass phrase will be shown on the screen as you type.

Using Private Keys with the SequeLink^® Proxy Server

The SSL cipher suites that use server authentication require a valid server certificate and associated private key. The SequeLink Proxy Server must access the private key from a private key file. Because it is not safe to store the private key as cleartext in a file, the SequeLink Proxy Server expects the private key to be stored in PKCS #8 format, which is a standard method of storing encrypted private keys when the encryption key is derived from a pass phrase.

Providing the Pass Phrase for the SequeLink^® Proxy Server

The SequeLink Proxy Server requires the pass phrase to start. The private key can be retrieved in either of the following ways:

When the SequeLink Proxy Server starts, it prompts for the private key. In graphical user interface (GUI) environments, a dialog box may appear. For example:





Type the pass phrase in the appropriate field of the dialog box and click OK.

In situations without a GUI, such as when the SequeLink Proxy Server is running in a terminal session on a UNIX machine, specify UsePassPhraseDialog=No in the proxy server configuration file. The SequeLink Proxy Server will use the standard input/output of your environment to prompt for the private key. When you type the pass phrase and press ENTER, the pass phrase displays on your standard output. When you are finished, make sure to scroll the output window so that unauthorized persons cannot see the pass phrase on your screen.

Code the pass phrase in the proxy server configuration file. Add the keyword=value pair:

PassPhrase=pass_phrase

where pass_phrase is the pass phrase required to access the private key. Leading and trailing blanks are stripped from the value when the pass phrase is retrieved from the configuration file; therefore, the pass phrase cannot have leading or trailing blanks in the configuration file. Make sure that only trusted accounts have access to the configuration file.

NOTE: If the SequeLink Proxy Server will be started as a Windows service, you must specify the pass phrase in the configuration file because the SequeLink Proxy Server cannot prompt for the pass phrase.

Storing the Private Key in PKCS #8 Format

If your private key is in cleartext format, you can use the encrypt.bat utility (on Windows) or the encrypt.sh shell script (on Linux/UNIX) to store the key in a file in PKCS #8 format.

The private keys are encrypted with triple DES with a 168-bit key derived from the pass phrase using a one-way hash function (SHA).

To provide sufficient randomness in the generated keys, you must provide sufficient randomness in the pass phrase. The English language has approximately 1.3 bits of randomness for each character; therefore, to provide 168 random bits for the two keys, you must have 130 characters (conservatively) of English text. Using punctuation characters and a mix of upper and lowercase letters, you can construct pass phrases that have more randomness with fewer characters.

Using the Encryption Tool

On Windows servers:

encrypt [-v virtual_machine] infile outfile 

where:

virtual_machine	is the executable name of the JVM that is installed on the machine where you encrypt the key. By default, this BAT file uses the J2SE JVM. If you want to use the Microsoft JVM, specify the optional parameter -v jview.
infile	is the name of the cleartext file.
outfile	is the name of the encrypted file.

On UNIX:

encrypt.sh infile outfile 

where:

infile	is the name of the cleartext file.
outfile	is the name of the encrypted file.

You may want to run the encryption tool on a machine other than the one running the SequeLink Proxy Server and transfer the encrypted file to the SequeLink Proxy Server host to avoid writing a copy of the private key in cleartext on the SequeLink Proxy Server host. Make sure that you transfer the complete proxy/lib directory to the machine on which you want to run the encryption tool.

The proxy server installation directory also contains a decryption tool that can be used to decrypt a file that has been encrypted with the encryption tool. The encryption and decryption tools prompt for the pass phrase and show it on the screen as you type, so make sure that you close the terminal session window after you have encrypted or decrypted the file to prevent unauthorized people from viewing it.

Using the Decryption Tool

On Windows servers:

decrypt [-v virtual_machine] infile outfile 

where:

virtual_machine	is the executable name of the JVM that is installed on the machine where you encrypt the key. By default, this BAT file uses the J2SE JVM. If you want to use the Microsoft JVM, specify the optional parameter -v jview.
infile	is the name of the encrypted file.
outfile	is the name of the cleartext file.

On UNIX:

decrypt.sh infile outfile 

where:

infile	is the name of the encrypted file.
outfile	is the name of the cleartext file.

Verifying the SequeLink^® Proxy Server Certificate

When you use a cipher suite that specifies server authentication, the SSL handshake protocol ensures that the server knows the private key that corresponds to the public key in the certificate. Subsequently, the client application must verify that the server is indeed the server with which it wants to communicate by verifying that the received certificate is the certificate that it expects from the server.

The JDBC application or applet provides the JDBC Client with a class that implements the com.ddtek.sequelink.cert.CertificateCheckerInterface interface. If you do not supply a class that implements this interface, the connection will be refused.

This interface is defined as:

package com.ddtek.sequelink.cert; 
public interface CertificateCheckerInterface 
   {  
   public void CheckCertificate(byte [][] certChain) 
      throws SecurityException; 
   } 

The JDBC driver calls this method and passes the X.509 certificate chain that it received during the SSL handshake to the method. All certificates are DER encoded and the server certificate is the first certificate in the array. The checkCertificate method must verify that the received certificate is trusted and is, for example, signed by a trusted authority. If the certificate is not trusted, the method must throw a Security Exception. You specify the name of the class that implements this interface in the certificateChecker keyword in the JDBC connection URL or the data source.

The driver/examples subdirectory contains the Java source files listed in Table 14-4 as examples of classes that implement CertificateCheckerInterface.

Table 14-4. Java Source Files Implementing CertificateCheckerInterface

Java Source File	Description
CheckAgainstCertificateFromJar.java	Adapt and use for downloaded applets.
CheckAgainstCertificateFromFile.java	Adapt and use for Java applications on a client machine.
KeyStoreCertificateChecker.java	Adapt and use for Java applications that use a Java keystore to verify that the provided certificate chain is trusted.

These classes retrieve the server certificate from a JAR file, or local file, and compare it with the certificate that is passed as the first element of the certChain parameter to the checkCertificate method. You can change these files as appropriate for your environment.

Coding the certificate you want to compare other certificates against in the downloaded applet is safe only if no one tampers with the applet while it is being downloaded from your Web server. You must use signed applets and you must configure your Web browser to explicitly check the signer of downloaded applets. Alternatively, you can use a secure and authenticated SSL connection to the web server when downloading the applet.

Using the Demo Certificates, Certificate Checker, and Private-Key Format Conversion Tool

SequeLink provides some demo applications in the installdir/proxy/demos directory, where installdir is your installation directory, that allow you to create or convert certificates.

Demo Certificates

The demo certificates that SequeLink provides are intended for testing purposes only and cannot be used to provide secure connections. Table 14-5 lists the private key files and describes the corresponding certificates.

Table 14-5. Demo Certificates  

File	Descriptions
demo-DSA-CA.cer	Demo Certificate Authority with a DSS X.509 certificate. This certificate is self signed.
demo-DSA-CA.pk8	Corresponding (PKCS #8 encrypted) private key of the public key provided by the certificate demo-DSA-CA.cer.
demo-DSA-server.p7b	Demo DSS server X.509 certificate signed with the public key provided by the certificate demo-DSA-CA.cer.
demo-DSA-server.pk8	Corresponding (PKCS #8 encrypted) private key of the public key provided by the certificate demo-DSA-server.cer.
demo-RSA-CA.cer	Demo Certificate Authority with an RSA X.509 certificate. This certificate is self signed.
demo-RSA-CA.pk8	Corresponding (PKCS #8 encrypted) private key of the public key provided by the certificate demo-RSA-CA.cer.
demo-RSA-server.p7b	Demo RSA server X.509 certificate signed with the public key provided by the demo-RSA-CA.cer.
demo-RSA-server.pk8	Corresponding (PKCS #8 encrypted) private key of the public key provided by the certificate demo-RSA-server.cer.

NOTES:

To use the demo certificates, you must add slssl.jar (if you are using J2SE 1.3) or slssl14.jar and iaik_jce_full.jar (if you are using J2SE 1.4 or higher) to your CLASSPATH variable.
You can re-generate demo certificates by running the following Java program in the installdir/proxy/ directory, where installdir is your installation directory:

java com.ddtek.sequelink.demo.GenerateDemoCertificates

You can customize the generation of these demo certificates by editing the demo.properties file in the installdir/proxy/demos/com/datadirect/sequelink/demo directory, where installdir is your installation directory.

The following examples show how to use the demo certificates:

Example A: Using SSL with an RSA Server Certificate

Start the SequeLink Proxy Server with the following configuration:

Port=9500

AdminPort=9600

Host=SequeLinkhost

ServerPort=SequeLinkport

Network=ssl

CipherSuites=SSL_DHE_RSA_WITH_3DES_EDE_CBC_SHA,SSL_
DHE_RSA_WITH_DES_CBC_SHA,SSL_RSA_WITH_3DES_EDE_CBC_
SHA,SSL_RSA_WITH_DES_CBC_SHA,SSL_RSA_WITH_RC4_128_MD5,
SSL_RSA_WITH_RC4_128_SHA

RSACertificate=cert/demo-RSA-server.p7b

RSAPrivateKey=cert/demo-RSA-server.pk8

PassPhrase=Demo Pass Phrase

where SequeLinkhost is the TCP/IP host name or address of the SequeLink Server and SequeLinkport is the port on which the SequeLink Server is listening for connection requests.

Make a connection to the SequeLink Server, for example, using DataDirect Test:

jdbc:sequelink:ssl://proxyserverhost:9500;
cipherSuites=SSL_RSA_WITH_RC4_128_MD5;
certificateChecker=com.ddtek.sequelink.cert.
AcceptAllCertificateChecker

where proxyserverhost is the IP address or symbolic host name of your proxy server host.

If successful, the following message appears:

Certificate accepted by

AcceptAllCertificateChecker.

*** ONLY FOR TESTING PURPOSES ***

Certificate chain:

1: O=SequeLink Demo Certificates, OU=Demo RSA

Server Certificate, CN=demo.ddtek.sequelink.com

2: O=SequeLink Demo Certificates, CN=Demo RSA CA

Certificate

Example B: Using SSL with a DSS Server Certificate

Start the proxy server with the following configuration:

Port=9500

AdminPort=9600

Host=SequeLinkhost

ServerPort=SequeLinkport

Network=ssl

CipherSuites=SSL_DHE_DSS_WITH_3DES_EDE_CBC_SHA,SSL_

DHE_DSS_WITH_DES_CBC_SHA,SSL_DHE_DSS_WITH_RC4_128_SHA

DSSCertificate=cert/demo-DSA-server.p7b

DSSPrivateKey=cert/demo-DSA-server.pk8

PassPhrase=Demo Pass Phrase

where SequeLinkhost is the TCP/IP host name or address of the SequeLink Server and SequeLinkport is the port on which the SequeLink Server is listening for connection requests.

Make a connection to the SequeLink Server, for example, using DataDirect Test:

jdbc:sequelink:ssl://proxyserverhost:9500;
cipherSuites=SSL_DHE_DSS_WITH_DES_CBC_SHA;
certificateChecker=com.ddtek.sequelink.cert.
AcceptAllCertificateChecker

where proxyserverhost is the IP address or symbolic host name of your proxy server host.

If successful, the following message appears:

Certificate accepted by

AcceptAllCertificateChecker.

*** ONLY FOR TESTING PURPOSES ***

Certificate chain:

1: O=SequeLink Demo Certificates, OU=Demo DSA

Server Certificate, CN=demo.sequelink.ddtek.com

2: O=SequeLink Demo Certificates, CN=Demo DSA CA

Certificate

Example C: Using SSL with Anonymous Cipher Suites (No Server Authentication)

Start the proxy server with the following configuration:

Port=9500

AdminPort=9600

Host=sequeLinkhost

ServerPort=sequelinkport

Network=ssl

CipherSuites=SSL_DH_anon_WITH_3DES_EDE_CBC_SHA,SSL_

DH_anon_WITH_DES_CBC_SHA,SSL_DH_anon_WITH_RC4_128_MD5

where sequeLinkhost is the TCP/IP host name or address of the SequeLink Server and sequelinkport is the port on which the SequeLink Server is listening for connection requests.

Make a connection to the SequeLink Server, for example, using DataDirect Test:

jdbc:sequelink:ssl://proxyserverhost:9500;
cipherSuites=SSL_DH_anon_WITH_DES_CBC_SHA

where proxyserverhost is the IP address or symbolic host name of your proxy server host.

Demo Certificate Checker

SequeLink provides a demo certificate checker that accepts all server certificates. It displays on the screen a warning and a description of the certificate the client received from the server through the SSL handshake. This certificate checker is implemented by the com.ddtek.sequelink.cert.AcceptAllCertificateChecker class.

Demo Private-Key Format Conversion Tool

SequeLink provides a private-key format conversion tool that can perform the following tasks:

Export a private key and X.509 certificate from a Java keystore (JKS) to an encrypted PKCS #8 private-key file and DER-encoded certificate file
Export a private key and X.509 certificate from a PKCS #12 keystore

The private-key format conversion tool is a command-line tool that uses the following syntax:

java.com.ddtek.sequelink.demo.KeyTool 
[-keystore keystore] 
[-alias alias] 
-certfile certfile 
-keyfile keyfile 
[-storetype storetype] 
[-storepass storepass] 
[-keypass keypass] 

where:

Parameter	Java Keystore (JKS) Export	PKCS #12 Keystore Export	Description
keystore	X	X	The file name of the JKS or the PKCS #12 keystore.
alias	X		The alias in the JKS. If supplied, it is assumed that the keystore parameter is a JKS.
certfile	X	X	The DER-encoded X.509 certificate file.
keyfile	X	X	The PKCS #8 encoded private key. The private key ends with the same password as the JKS or the PKCS #12 keystore.
storetype	X	X	The type of JKS. The default is jks. This parameter is optional.
storepass	X		The password used to protect the JKS or the PKCS #12 keystore. If omitted, you will be prompted for this password.
keypass	X		The password that protects the JKS key entry. This parameter is required when the password for the key entry is different from the keystore password.

To use the demo private-key format conversion tool, you must add slssl14.jar and iaik_jce_full.jar to your CLASSPATH variable.